<!DOCTYPE html>
<html>

<head>
  <title>Quarkus - Security Architecture and Guides</title>
  <script id="adobe_dtm" src="https://www.redhat.com/dtm.js" type="text/javascript"></script>
  <script src="/assets/javascript/highlight.pack.js" type="text/javascript"></script>
  <META HTTP-EQUIV='Content-Security-Policy' CONTENT="default-src 'none'; script-src 'self' 'unsafe-eval' 'sha256-ANpuoVzuSex6VhqpYgsG25OHWVA1I+F6aGU04LoI+5s=' 'sha256-ipy9P/3rZZW06mTLAR0EnXvxSNcnfSDPLDuh3kzbB1w=' js.bizographics.com https://www.redhat.com assets.adobedtm.com jsonip.com https://ajax.googleapis.com https://www.googletagmanager.com https://www.google-analytics.com https://use.fontawesome.com; style-src 'self' https://fonts.googleapis.com https://use.fontawesome.com; img-src 'self' *; media-src 'self' ; frame-src https://www.googletagmanager.com https://www.youtube.com; frame-ancestors 'none'; base-uri 'none'; object-src 'none'; form-action 'none'; font-src 'self' https://use.fontawesome.com https://fonts.gstatic.com;">
  <META HTTP-EQUIV='X-Frame-Options' CONTENT="DENY">
  <META HTTP-EQUIV='X-XSS-Protection' CONTENT="1; mode=block">
  <META HTTP-EQUIV='X-Content-Type-Options' CONTENT="nosniff">
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="description" content="Quarkus: Supersonic Subatomic Java">
  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@QuarkusIO"> 
  <meta name="twitter:creator" content="@QuarkusIO">
  <meta property="og:url" content="https://quarkus.io/guides/security" />
  <meta property="og:title" content="Quarkus - Security Architecture and Guides" />
  <meta property="og:description" content="Quarkus: Supersonic Subatomic Java" />
  <meta property="og:image" content="/assets/images/quarkus_card.png" />
  <link rel="canonical" href="https://quarkus.io/guides/security">
  <link rel="shortcut icon" type="image/png" href="/favicon.ico" >
  <link rel="stylesheet" href="https://quarkus.io/guides/stylesheet/config.css" />
  <link rel="stylesheet" href="/assets/css/main.css" />
  <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.1.0/css/all.css" integrity="sha384-lKuwvrZot6UHsBSfcMvOkWwlCMgc0TaWr+30HWe3a4ltaBwTZhyTEggF5tJv8tbt" crossorigin="anonymous">
  <link rel="alternate" type="application/rss+xml"  href="https://quarkus.io/feed.xml" title="Quarkus">
  <script src="https://quarkus.io/assets/javascript/goan.js" type="text/javascript"></script>
  <script src="https://quarkus.io/assets/javascript/hl.js" type="text/javascript"></script>
</head>

<body class="guides">
  <!-- Google Tag Manager (noscript) -->
  <noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-NJWS5L"
  height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
  <!-- End Google Tag Manager (noscript) -->

  <div class="nav-wrapper">
  <div class="grid-wrapper">
    <div class="width-12-12">
      <input type="checkbox" id="checkbox" />
      <nav id="main-nav" class="main-nav">
  <div class="container">
    <div class="logo-wrapper">
      
        <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_600px_reverse.png" class="project-logo" title="Quarkus"></a>
      
    </div>
    <label class="nav-toggle" for="checkbox">
      <i class="fa fa-bars"></i>
    </label>
    <div id="menu" class="menu">
      <span>
        <a href="/get-started/" class="">Get Started</a>
      </span>
      <span>
        <a href="/guides/" class="active">Guides</a>
      </span>
      <span>
        <a href="/community/" class="">Community</a>
      </span>
      <span>
        <a href="/support/" class="">Support</a>
      </span>
      <span>
        <a href="/blog/" class="">Blog</a>
      </span>
      <span>
        <a href="https://code.quarkus.io" class="button-cta secondary white">Start Coding</a>
      </span>
    </div>
  </div>
      </nav>
    </div>
  </div>
</div>

  <div class="content">
    <div class="guide">
  <div class="width-12-12">
    <h1 class="text-caps">Quarkus - Security Architecture and Guides</h1>
    <div class="hide-mobile toc"><ul class="sectlevel1">
<li><a href="#architecture">Architecture</a></li>
<li><a href="#authentication-mechanisms">Authentication mechanisms</a>
<ul class="sectlevel2">
<li><a href="#basic-and-form-authentication-mechanisms">Basic and Form Authentication Mechanisms</a></li>
<li><a href="#mutual-tls-authentication">Mutual TLS Authentication</a></li>
</ul>
</li>
<li><a href="#openid-connect">OpenId Connect</a></li>
<li><a href="#smallrye-jwt">SmallRye JWT</a></li>
<li><a href="#oauth2">OAuth2</a></li>
<li><a href="#ldap">LDAP</a></li>
<li><a href="#identity-providers">Identity Providers</a></li>
<li><a href="#combining-authentication-mechanisms">Combining Authentication Mechanisms</a></li>
<li><a href="#proactive-authentication">Proactive Authentication</a></li>
<li><a href="#authorization">Authorization</a></li>
<li><a href="#customization-and-other-useful-tips">Customization and other useful tips</a></li>
<li><a href="#testing">Testing</a></li>
<li><a href="#secret-engines">Secret Engines</a></li>
</ul></div>
    <div>
      <div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus Security provides the architecture, multiple authentication and authorization mechanisms, and other tools for the developers to build a production-quality security for their Quarkus applications.</p>
</div>
<div class="paragraph">
<p>This document provides a brief overview of Quarkus Security and links to the individual guides.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="architecture"><a class="anchor" href="#architecture"></a>Architecture</h2>
<div class="sectionbody">
<div class="paragraph">
<p><code>HttpAuthenticationMechanism</code> is the main entry into Quarkus HTTP Security.</p>
</div>
<div class="paragraph">
<p>Quarkus Security Manager uses <code>HttpAuthenticationMechanism</code> to extract the authentication credentials from the HTTP request and delegates to <code>IdentityProvider</code> to
complete the conversion of these credentials to <code>SecurityIdentity</code>.</p>
</div>
<div class="paragraph">
<p>For example, the credentials may be coming with the HTTP <code>Authorization</code> header, client HTTPS certificates or cookies.</p>
</div>
<div class="paragraph">
<p><code>IdentityProvider</code> verifies the authentication credentials and maps them to <code>SecurityIdentity</code> which contains the user name, roles, the original authentication credentials, and other attributes.</p>
</div>
<div class="paragraph">
<p>For every authenticated resource, you can inject a <code>SecurityIdentity</code> instance to get the authenticated identity information.</p>
</div>
<div class="paragraph">
<p>In some other contexts you may have other parallel representations of the same information (or parts of it) such as <code>SecurityContext</code>
for JAX-RS or <code>JsonWebToken</code> for JWT.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="authentication-mechanisms"><a class="anchor" href="#authentication-mechanisms"></a>Authentication mechanisms</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus supports several sources to load authentication information from.</p>
</div>
<div class="sect2">
<h3 id="basic-and-form-authentication-mechanisms"><a class="anchor" href="#basic-and-form-authentication-mechanisms"></a>Basic and Form Authentication Mechanisms</h3>
<div class="paragraph">
<p>Basic and Form HTTP-based authentication mechanisms are the core authentication mechanisms supported in Quarkus.
Please see <a href="security-built-in-authentication#basic-auth">Basic HTTP Authentication</a> and <a href="security-built-in-authentication#form-auth">Form HTTP Authentication</a> for more information.</p>
</div>
</div>
<div class="sect2">
<h3 id="mutual-tls-authentication"><a class="anchor" href="#mutual-tls-authentication"></a>Mutual TLS Authentication</h3>
<div class="paragraph">
<p>Quarkus provides Mutual TLS authentication so that you can authenticate users based on their X.509 certificates.</p>
</div>
<div class="paragraph">
<p>Please see <a href="security-built-in-authentication#mutual-tls">Mutual TLS Authentication</a> for more information.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="openid-connect"><a class="anchor" href="#openid-connect"></a>OpenId Connect</h2>
<div class="sectionbody">
<div class="paragraph">
<p><code>quarkus-oidc</code> extension provides a reactive, interoperable, multi-tenant enabled OpenId Connect adapter which supports <code>Bearer Token</code> and <code>Authorization Code Flow</code> authentication mechanisms.</p>
</div>
<div class="paragraph">
<p><code>Bearer Token</code> mechanism extracts the token from HTTP <code>Authorization</code> header.
<code>Authorization Code Flow</code> mechanism uses OpenId Connect Authorization Code flow. It redirects the user to IDP to authenticate and completes the authentication process after the user has been redirected back to Quarkus by exchanging the provided code grant for ID, access and refresh tokens.</p>
</div>
<div class="paragraph">
<p>ID and access <code>JWT</code> tokens are verified with the refreshable <code>JWK</code> key set but both JWT and opaque (binary) tokens can be introspected remotely.</p>
</div>
<div class="paragraph">
<p>See the <a href="security-openid-connect">Using OpenID Connect to Protect Service Applications</a> guide for more information about <code>Bearer Token</code> authentication mechanism.</p>
</div>
<div class="paragraph">
<p>See the <a href="security-openid-connect-web-authentication">Using OpenID Connect to Protect Web Application</a> guide for more information about <code>Authorization Code Flow</code> authentication mechanism.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
<div class="paragraph">
<p>Both <code>quarkus-oidc</code> <code>Bearer</code> and <code>Authorization Code Flow</code> Authentication mechanisms use  <a href="#smallrye-jwt">SmallRye JWT</a> to represent JWT tokens as Microprofile JWT <code>org.eclipse.microprofile.jwt.JsonWebToken</code>.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>See <a href="security-openid-connect-multitenancy">Using OpenID Connect Multi-Tenancy</a> for more information about multiple tenants which can support <code>Bearer</code> or <code>Authorization Code Flow</code> authentication mechanism and configured statically or dynamically.</p>
</div>
<div class="paragraph">
<p>If you use Keycloak and Bearer tokens then also see the <a href="security-keycloak-authorization">Using Keycloak to Centralize Authorization</a> guide.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="smallrye-jwt"><a class="anchor" href="#smallrye-jwt"></a>SmallRye JWT</h2>
<div class="sectionbody">
<div class="paragraph">
<p><code>quarkus-smallrye-jwt</code> provides Microprofile JWT 1.1.1 implementation and many more options to verify signed and encrypted <code>JWT</code> tokens and represent them as <code>org.eclipse.microprofile.jwt.JsonWebToken</code>.</p>
</div>
<div class="paragraph">
<p>It provides an alternative to <code>quarkus-oidc</code> Bearer Token Authentication Mechanism. It can currently verify only <code>JWT</code> tokens using the PEM keys or refreshable <code>JWK</code> key set.</p>
</div>
<div class="paragraph">
<p>Additionally it provides <code>JWT Generation API</code> for creating <code>signed</code>, <code>inner-signed</code> and/or <code>encrypted</code> <code>JWT</code> tokens with ease.</p>
</div>
<div class="paragraph">
<p>See the <a href="security-jwt">Using SmallRye JWT</a> guide for more information.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="oauth2"><a class="anchor" href="#oauth2"></a>OAuth2</h2>
<div class="sectionbody">
<div class="paragraph">
<p><code>quarkus-elytron-security-oauth2</code> provides an alternative to <code>quarkus-oidc</code> Bearer Token Authentication Mechanism. It is based on <code>Elytron</code> and is primarily meant for introspecting the opaque tokens remotely.</p>
</div>
<div class="paragraph">
<p>See the <a href="security-oauth2">Using OAuth2</a> guide for more information.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="ldap"><a class="anchor" href="#ldap"></a>LDAP</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Please see the <a href="security-ldap">Authenticate with LDAP</a> guide for more information about LDAP authentication mechanism.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="identity-providers"><a class="anchor" href="#identity-providers"></a>Identity Providers</h2>
<div class="sectionbody">
<div class="paragraph">
<p><code>IdentityProvider</code> converts the authentication credentials provided by <code>HttpAuthenticationMechanism</code> to <code>SecurityIdentity</code>.</p>
</div>
<div class="paragraph">
<p>Some extensions such as <code>OIDC</code>, <code>OAuth2</code>, <code>SmallRye JWT</code>, <code>LDAP</code> have the inlined <code>IdentityProvider</code> implementations which are specific to the supported authentication flow.
For example, <code>quarkus-oidc</code> uses its own <code>IdentityProvider</code> to convert a token to <code>SecurityIdentity</code>.</p>
</div>
<div class="paragraph">
<p>If you use <code>Basic</code> or <code>Form</code> HTTP-based authentication then you have to add an <code>IdentityProvider</code> which can convert a user name and password to <code>SecurityIdentity</code>.</p>
</div>
<div class="paragraph">
<p>See <a href="security-jpa">JPA IdentityProvider</a> and <a href="security-jdbc">JDBC IdentityProvider</a> for more information.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="combining-authentication-mechanisms"><a class="anchor" href="#combining-authentication-mechanisms"></a>Combining Authentication Mechanisms</h2>
<div class="sectionbody">
<div class="paragraph">
<p>One can combine multiple authentication mechanisms if they get the authentication credentials from the different sources.
For example, combining built-in <code>Basic</code> and <code>quarkus-oidc</code> <code>Bearer</code> authentication mechanisms is allowed, but combining <code>quarkus-oidc</code> <code>Bearer</code> and <code>smallrye-jwt</code> authentication mechanisms is not allowed because both will attempt to verify the token extracted from the HTTP <code>Authorization Bearer</code> scheme.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="proactive-authentication"><a class="anchor" href="#proactive-authentication"></a>Proactive Authentication</h2>
<div class="sectionbody">
<div class="paragraph">
<p>By default, Quarkus does what we call proactive authentication. This means that if an incoming request has a
credential then that request will always be authenticated (even if the target page does not require authentication).</p>
</div>
<div class="paragraph">
<p>See <a href="security-built-in-authentication#proactive-authentication">Proactive Authentication</a> for more information.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="authorization"><a class="anchor" href="#authorization"></a>Authorization</h2>
<div class="sectionbody">
<div class="paragraph">
<p>See <a href="security-authorization">Security Authorization</a> for more information about Role Based Access Control and other authorization options.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="customization-and-other-useful-tips"><a class="anchor" href="#customization-and-other-useful-tips"></a>Customization and other useful tips</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus Security is highly customizable. One can register custom <code>HttpAuthenticationMechanism</code>s, <code>IdentityProvider</code>s and <code>SecurityidentityAugmentor</code>s.</p>
</div>
<div class="paragraph">
<p>See <a href="security-customization">Security Customization</a> for more information about customizing Quarkus Security and other useful tips about the reactive security, registering the security providers, etc.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="testing"><a class="anchor" href="#testing"></a>Testing</h2>
<div class="sectionbody">
<div class="paragraph">
<p>See <a href="security-testing">Security Testing</a> for more information about testing Quarkus Security.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="secret-engines"><a class="anchor" href="#secret-engines"></a>Secret Engines</h2>
<div class="sectionbody">
<div class="paragraph">
<p>Quarkus provides a very comprehensive HashiCorp Vault support, please see the <a href="vault">Quarkus and HashiCorp Vault</a> documentation for more information.</p>
</div>
</div>
</div>
    </div>
  </div>
</div>

  </div>

  <div class="content project-footer">
  <div class="footer-section">
    <div class="logo-wrapper">
      <a href="/"><img src="/assets/images/quarkus_logo_horizontal_rgb_reverse.svg" class="project-logo" title="Quarkus"></a>
    </div>
  </div>
  <div class="grid-wrapper">
    <p class="grid__item width-3-12">Quarkus is open. All dependencies of this project are available under the <a href='https://www.apache.org/licenses/LICENSE-2.0' target='_blank'>Apache Software License 2.0</a> or compatible license.<br /><br />This website was built with <a href='https://jekyllrb.com/' target='_blank'>Jekyll</a>, is hosted on <a href='https://pages.github.com/' target='_blank'>Github Pages</a> and is completely open source. If you want to make it better, <a href='https://github.com/quarkusio/quarkusio.github.io' target='_blank'>fork the website</a> and show us what you’ve got.</p>

    
      <div class="width-1-12 project-links">
        <span>Navigation</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="/">Home</a></li>
          
            <li><a href="/guides">Guides</a></li>
          
            <li><a href="/community/#contributing">Contribute</a></li>
          
            <li><a href="/faq">FAQ</a></li>
          
            <li><a href="/get-started">Get Started</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Contribute</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://twitter.com/quarkusio">Follow us</a></li>
          
            <li><a href="https://github.com/quarkusio">GitHub</a></li>
          
            <li><a href="/security">Security&nbsp;policy</a></li>
          
        </ul>
      </div>
    
      <div class="width-1-12 project-links">
        <span>Get Help</span>
        <ul class="footer-links width-1-12">
          
            <li><a href="https://groups.google.com/forum/#!forum/quarkus-dev">Forums</a></li>
          
            <li><a href="https://quarkusio.zulipchat.com">Chatroom</a></li>
          
        </ul>
      </div>
    

    
      <div class="width-3-12 more-links">
        <span>Quarkus is made of community projects</span>
        <ul class="footer-links">
          
            <li><a href="https://vertx.io/" target="_blank">Eclipse Vert.x</a></li>
          
            <li><a href="https://microprofile.io" target="_blank">Eclipse MicroProfile</a></li>
          
            <li><a href="https://hibernate.org" target="_blank">Hibernate</a></li>
          
            <li><a href="https://netty.io" target="_blank">Netty</a></li>
          
            <li><a href="https://resteasy.github.io" target="_blank">RESTEasy</a></li>
          
            <li><a href="https://camel.apache.org" target="_blank">Apache Camel</a></li>
          
            <li><a href="https://code.quarkus.io/" target="_blank">And many more...</a></li>
          
        </ul>
      </div>
    
  </div>
</div>
  <div class="content redhat-footer">
  <div class="grid-wrapper">
    <span class="licence">
      <i class="fab fa-creative-commons"></i><i class="fab fa-creative-commons-by"></i> <a href="https://creativecommons.org/licenses/by/3.0/" target="_blank">CC by 3.0</a> | <a href="https://www.redhat.com/en/about/privacy-policy">Privacy Policy</a>
    </span>
    <span class="redhat">
      Sponsored by
    </span>
    <span class="redhat-logo">
      <a href="https://www.redhat.com/" target="_blank"><img src="/assets/images/redhat_reversed.svg"></a>
    </span>
  </div>
</div>


  <script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.4/jquery.min.js" integrity="sha384-8gBf6Y4YYq7Jx97PIqmTwLPin4hxIzQw5aDmUg/DDhul9fFpbbLcLh3nTIIDJKhx" crossorigin="anonymous"></script>
  <script type="text/javascript" src="/assets/javascript/mobile-nav.js"></script>
  <script type="text/javascript" src="/assets/javascript/scroll-down.js"></script>
  <script src="/assets/javascript/satellite.js" type="text/javascript"></script>
  <script src="https://quarkus.io/guides/javascript/config.js" type="text/javascript"></script>
  <script src="/assets/javascript/search-filter.js" type="text/javascript"></script>
  <script src="/assets/javascript/back-to-top.js" type="text/javascript"></script>
</body>

</html>
